<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<link href="Doc.css" rel="stylesheet"/>
<title>TreeGrid - Data server changes</title>
</head>
<body>
<div class="Doc">


<h1>Changing data from server</h1>
<p>TreeGrid documentation</p>

<!-------------------------------------------------------  XML structure with downloaded changes  ------------------------------------------------->
<a name="XMLChanges"></a>
<h2>XML structure with downloaded changes</h2>

Data sent from server to grid. It is generated by server script.<br />
Used to change the rows and their cells one by one from server side.<br />
Used when downloading changes done on server after uploading (from <b>Upload</b> source) or checking for updates (from <b>Check</b> source) or downloading cell (from <b>Cell</b> source).<br />
Used as <b>response</b> from data sources <b>Upload</b>, <b>Check</b>, <b>Cell</b>.<br /><br />

<i>Only these <b>row attributes</b> are supported:</i><br /> 
    <div class="L2">
    Deleted, Added, Moved, Changed, Parent, Next, Prev<br />
	  Def, Color, AlternateColor, Class<br />
    CanEdit, CanFocus, CanDelete, CanSelect, CanExpand<br />
    Visible, Selected, Expanded, Menu<br />
    Calculated, CalcOrder<br />
    Height <i>(since 14.0)</i><br />
    </div><br />
    
<i>Only these <b>cell attributes</b> are supported:</i><br /> 
    <div class="L2">  	
    <i>value</i><br />
  	Class, Color, HtmlPrefix, HtmlPostfix, Visible<br />
  	CanEdit, CanFocus<br />
  	Type, Range, Format, EditFormat, ExportFormat, EditMask, ResultMask, Size<br />
  	Button, ButtonText, Defaults, Suggest, SuggestType,<br /> 
   Enum, EditEnum, EnumKeys, IntFormat, Related Refresh, Clear,<br />
  	Tip, ToolTip, Error, Selected, Formula, Menu, CopyTo<br />
   </div><br />    
<i>Since 12.0 also attributes set in <a href="CellEdit.htm#CfgEditAttrs"><b>EditAttrs</b></a> are supported</i><br />
<br />
To change <a href="#Iid">id</a> attribute of existing row, return it in <a href="#INewId">NewId</a> attribute.<br />    

<!-- Update -->
<a name="ChangesUpdate"></a>
<div class="XML">
   <u>chg <b>9.0</b> <i>upd <b>13.0</b></i></u> <b>&lt;Changes></b> <i>int</i>
   <h4>Update</h4> <s>[1]</s>
</div>
What to update after rows are changed/added/deleted/moved. Binary array.<br />
1.bit (<b>&1</b>) - accepts row changes. The row is displayed as unchanged (all the change flags are removed, Deleted rows are removed).<br />
  <div class="L2">
  <i>Since 9.0 for Update=1 it does not accept other pending changes in the row, use Update=17 to do it.</i>
  </div>
2.bit (<b>&2</b>) - reserved <i>(since 9.0 it always recalculates the rows)</i><br />
3.bit (<b>&4</b>) - filter row. <i>works only for <a href="Filter.htm#CfgStandardFilter">StandardFilter</a>=<b>0</b></i><br />
4.bit (<b>&8</b>) - search row (only Select or Mark actions)<br /> 
5.bit (<b>&16</b>) - accept all pending changes <u>before</u> processing the &lt;Changes> tag.<br /> 
  <div class="L2">
  Use this setting in Upload_Response to accept the old changes and create new not saved changes.<br />
	The response should return also return negative &lt;IO Result/> to not accept changes later.<br />
  </div>
6.bit (<b>&32</b>) - <i>(new 9.3)</i> does not refresh the change cell(s). Usable for changing edited cell from server side.<br />
7.bit (<b>&64</b>) - <i>(new 12.0)</i> searches updated row id against <a href="RowBasics.htm#CfgRowIndex">RowIndex</a> instead of row id. <u>Not</u> for Added, Moved and Deleted rows.<br /><br />
8.bit (<b>&128</b>) - <i>(new 12.0)</i> adds new pages due <a href="Paging.htm#CfgAutoPages">AutoPages</a> if the updated row does not exist.<br />
9.bit (<b>&256</b>) - <i>(new 13.0)</i> animates all changes done from server side, see <a href="Animations.htm#ServerAnimations">Animations for server side changes</a>.<br />

<!-- ChangesUpdate -->
<a name="CfgChangesUpdate"></a>
<div class="XML">
   <u>new <b>9.0</b></u> <b>&lt;Cfg></b> <i>int</i>
   <h4>ChangesUpdate</h4> <s>[1]</s>
</div>
Default value for <a href="#ChangesUpdate">Update</a> used if &lt;Changes Update/> is not set.<br />
It can be used also in JSON format, because the &lt;Changes Update/>attribute is not available in JSON.<br />

<!-- Added -->
<a name="ChangesUpdate"></a>
<div class="XML">
   <u>new <b>14.0</b></u> <b>&lt;Changes></b> <i>int</i>
   <h4>Added</h4> <s>[0]</s>
</div>
What to do when adding row that already exists in the grid.<br />
<b>0</b> - Update the old row with attributes from new row<br />
<b>1</b> - Delete old row and add the new row<br />
<b>2</b> - Discard adding the new row and preserve old row<br />
<b>3</b> - Add new row with newly generated id<br />
<b>4</b> - Generate new id for the old row<br />

<!-- ChangesAdded -->
<a name="CfgChangesAdded"></a>
<div class="XML">
   <u>new <b>14.0</b></u> <b>&lt;Cfg></b> <i>int</i>
   <h4>ChangesAdded</h4> <s>[0]</s>
</div>
Default value for <a href="#ChangesAdded">Added</a> used if &lt;Changes Added/> is not set.<br />
It can be used also in JSON format, because the &lt;Changes Added/>attribute is not available in JSON.<br />

<!-- id -->
<a name="Iid"></a>
<div class="XML">
   <u></u> <b>&lt;I></b> <i>string</i>
   <h4>id</h4> <s><i>Both letters lowercase!</i></s>
</div>
Unique ID of the row to change or new ID for the added row.<br />

<!-- NewId -->
<a name="INewId"></a>
<div class="XML">
   <u></u> <b>&lt;I></b> <i>string</i>
   <h4>NewId</h4> <s></s>
</div>
New <a href="#Iid">id</a> for the row when it is modified by &lt;Changes> tag.<br />

<!-- OnUpdateRow -->
<a name="OnUpdateRow"></a>
<div class="API">
   <u></u> <b>API event</b> <i>void</i>
   <h4>OnUpdateRow</h4>
   <s>(<i>TGrid</i> <b>grid</b>, <i>TRow</i> <b>row</b>, <i>TRow</i> <b>update</b>)</s>
</div>
Called after the row is updated or added from server side.<br /> 
The <b>update</b> is virtual row with the changes applied to the <b>row</b>. The <b>update</b> is a node from &lt;Changes> tag.<br />
Can be used to refresh changed row or provide some custom changes according to custom settings in the <b>update</b>.<br /><br />


<tt style="font-size:150%;color:red;">&lt;<b style="color:blue;">Grid</b>></tt> (Root tag, can accept any count of introduced child tags in any order)<br /><br />
  <div class="L1">
  <tt style="font-size:150%;color:red;">&lt;<b style="color:blue;">IO</b></tt> ... attributes ... <tt style="font-size:150%;color:red;">/></tt> (a server response)<br /><br />

  <tt style="font-size:150%;color:red;">&lt;<b style="color:blue;">Changes</b></tt> <b>Update</b>='1' <tt style="font-size:150%;color:red;">></tt> (list of changed rows)
    <div class="L1">
    <tt style="font-size:150%;color:red;">&lt;<b style="color:blue;">I</b></tt> <b>id</b>='...'  <i>... <b>some</b> row and cell attributes ...</i> <tt style="font-size:150%;color:red;">/></tt><br /> 
    <i>... More tags &lt;I> ...</i><br />
    </div> 
  <tt style="font-size:150%;color:red;">&lt;/<b style="color:blue;">Changes</b>></tt>
  </div>
<tt style="font-size:150%;color:red;">&lt;/<b style="color:blue;">Grid</b>></tt>
 
<!------------------------------------------------  XML structure with request for a cell  ------------------------------------------------->
<a name="XMLRequest"></a>
<h2>XML structure with request for a cell</h2>

Used as <b>request sent</b> to data source <b>Cell</b>.<br /> 
It is used to download <b>Defaults list</b> dynamically from server (when set <tt><b>DefaultsServer</b>='1'</tt>), before the list is expanded.<br />
It is used to download <b>cell settings</b> dynamically from server (when set <tt><b>EditServer</b>='1'</tt>), before it is edited.<br />
It is used to download <b>Suggest list</b> dynamically from server (when set <tt><b>SuggestServer</b>='1'</tt>), whenever cell value is changed while editing it to update the suggest list.

<!-- Cell_Url -->
<a name="Cell_Url"></a>
<div class="XML">
   <u></u> <b style="margin-left:-20px;width:115px;">&lt;treegrid,bdo></b> <i>string</i>
   <h4>Cell_Url</h4> <s></s>
</div>
An URL to download changes from server for given cell before defined action happens.<br />
Used to download:<br />
  <div class="L2">
	Defaults list when set <tt><a href="CellEdit.htm#CDefaultsServer">DefaultsServer</a>='1'</tt>. Called before the list is displayed on click to the Defaults button.<br />
	Suggest list when set <tt><a href="CellEdit.htm#CSuggestServer">SuggestServer</a>='1'</tt>. Called during editing whenever user changes the input value to get new list for suggested values.<br />
	Edit settings when set <tt><a href="CellEdit.htm#CEditServer">EditServer</a>='1'</tt>. Called before editing  started.<br />
  </div>
The XML request has format like <tt>&lt;Grid> ... &lt;Body>&lt;B id='row_id' Col='column_name' Val='cell_value'/>&lt;/Body>&lt;/Grid></tt><br />
The returned data should be like other server returns in &lt;<a href="">Changes</a>> tag.<br /><br />


<tt style="font-size:150%;color:red;">&lt;<b style="color:blue;">Grid</b>></tt><br /><br /> 

  <div class="L1">
  <tt style="font-size:150%;color:red;">&lt;<b style="color:blue;">IO</b></tt> <i>... attributes with request settings  ...</i> <tt style="font-size:150%;color:red;">/></tt> (<a href="DataCommunication.htm#IOSession">Session</a> attribute)<br />
  <span style="float:left;">
  <tt style="font-size:150%;color:red;">&lt;<b style="color:blue;">Cfg</b></tt> <i>... attributes with grid settings read from cookies  ...</i> <tt style="font-size:150%;color:red;">/></tt>&nbsp;
  </span> 
    <div style="float:left;">
    (Sort, Group, ReSort, ReCalc, TimeZone attributes)<br />
    (SearchAction, SearchExpression, SearchType, SearchMethod, SearchDefs, SearchCols attributes)<br />
  	(Focused, FocusedCol, FocusedPos attributes)<br />
    </div>
  <div style="clear:both;"><tt style="font-size:150%;color:red;">&lt;<b style="color:blue;">Filters</b>></tt> (list of filters)</div>
    <div class="L1">
    <tt style="font-size:150%;color:red;">&lt;<b style="color:blue;">I</b></tt> <i>... row and cell attributes ...</i> <tt style="font-size:150%;color:red;">/></tt> (<b>id</b> attribute, cell <b>values</b> and cell <b>Filter</b> attributes)<br />
    <i>... More tags &lt;I> if more filters are in grid  ...</i><br /> 
    </div>
  <tt style="font-size:150%;color:red;">&lt;/<b style="color:blue;">Filters</b>></tt><br /><br />
    
  <tt style="font-size:150%;color:red;">&lt;<b style="color:blue;">Body</b>></tt> 
    <div class="L1">
    <tt style="font-size:150%;color:red;">&lt;<b style="color:blue;">B</b></tt> <i>... attributes identifying the cell ...</i> <tt style="font-size:150%;color:red;">/></tt> (<b>id</b> attribute, <b>Col</b> attribute as column name, <b>Val</b> attribute as the cell value)
    </div>
  <tt style="font-size:150%;color:red;">&lt;/<b style="color:blue;">Body</b>></tt>
  </div><br /> 

<tt style="font-size:150%;color:red;">&lt;/<b style="color:blue;">Grid</b>></tt> 

<!------------------------------------------------  Synchronizing data with server  ------------------------------------------------->
<a name="Synchronizing"></a>
<h2>
Synchronizing data with server<br />
(periodical check / server push / long polling)
</h2>

With TreeGrid you can do client data synchronization with server. When server gets some change from another source (e.g. another client), TreeGrid automatically downloads the changes and updates its data on client.<br /><br />

Set <a href="#Check_Url">Check_Url</a> to server script url that will return all changes (in &lt;<a href="#XMLChanges">Changes</a>> tag) done on server from the last access to the <a href="#Check_Url">Check_Url</a>.<br /> 
You can set also other attributes with <b>Check_</b> prefix (like <b>Check_Method</b>) to control how the communication will be done.<br />
There are two usual methods of synchronization, periodical check and long polling.<br /><br />

a) <b><u>Periodical checking</u></b><br />
Set <a href="#Check_Interval">Check_Interval</a> to some interval (in seconds) and TreeGrid will periodically download changes from <a href="#Check_Url">Check_Url</a>.<br /> 
When no changes have been done since last call, server will just return empty response.<br /><br />

b) <b><u>Long polling</u></b> (simulates server <b>Push</b> technology)<br />
<i>This method provides immediate response, the changes on server are immediately downloaded to client.</i><br />
Set <tt><a href="#Check_Interval">Check_Interval</a>='<b>1</b>'</tt> and <tt><a href="#Check_Timeout">Check_Timeout</a>='<b>0</b>'</tt> and TreeGrid will periodically and immediately download changes from <a href="#Check_Url">Check_Url</a>.<br />
When no changes have been done since last call, server will <u>not</u> return anything and <b>let the HTTP connection open</b> until some changes arrive.<br /> 
You need to permit the long polling on your server, increase the connection timeouts.<br />
You can also set <tt><a href="#Check_Repeat">Check_Repeat</a>="<b>3</b>"</tt> to resend the request automatically when server closes the connection due its timeout.<br />

<!-- Check_Url -->
<a name="Check_Url"></a>
<div class="XML">
   <u></u> <b style="margin-left:-20px;width:115px;">&lt;treegrid,bdo></b> <i>string</i>
   <h4>Check_Url</h4> <s></s>
</div>
If set, TreeGrid periodically checks this URL and downloads changes from server (if any) and add them to TreeGrid.<br />

<!-- Check_Timeout -->
<a name="Check_Timeout"></a>
<div class="XML">
   <u></u> <b style="margin-left:-20px;width:115px;">&lt;treegrid,bdo></b> <i>string</i>
   <h4>Check_Timeout</h4> <s>[0]</s>
</div>
How long will the grid wait for response, in seconds.<br />
<b>0</b> means forever, use especially for <b>long polling</b>.<br />

<!-- Check_Interval -->
<a name="Check_Interval"></a>
<div class="XML">
   <u></u> <b style="margin-left:-20px;width:115px;">&lt;treegrid,bdo></b> <i>string</i>
   <h4>Check_Interval</h4> <s>[5] Saved to cookies, to not load it set <tt><b>CheckIntervalLap</b>='1'</tt></s>
</div>
How often grid will check for updates on <a href="#Check_Url">Check_Url</a>. In seconds.<br />
This value can be modified by a user from configuration menu.<br />

<!-- Check_Repeat -->
<a name="Check_Repeat"></a>
<div class="XML">
   <u></u> <b style="margin-left:-20px;width:115px;">&lt;treegrid,bdo></b> <i>string</i>
   <h4>Check_Repeat</h4> <s>[3]</s>
</div>
What to do if server returns an error.<br />
<b>0</b> - alerts the problem to user ("Synchronizing with server failed!"), and disables the <tt>Check_Interval='0'</tt><br />
<b>1</b> - does not alert anything to user, just disables the <tt>Check_Interval='0'</tt><br />
<b>2</b> - alerts the problem to user ("Synchronizing with server failed! Do you want to temporary disable the checking for updates?") and let him to choose.<br /> 
<b>3</b> - Automatically repeats the attempt<br />

<!-- CheckForUpdates -->
<a name="CheckForUpdates"></a>
<div class="API">
   <u></u> <b>API method</b> <i>void</i>
   <h4>CheckForUpdates</h4>
   <s>(<i>function</i> <b>Func</b>)</s>
</div>
Checks for updates on server at <a href="#Check_Url">Check_Url</a> and downloads them if any. Calls <b>Func</b> after finish.<br />

</div>
</body>	
</html>